<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>nl</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_001_014_1536">&nbsp;</a>NAME</h4><blockquote>
nl - line numbering filter
</blockquote><h4><a name = "tag_001_014_1537">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

nl <b>[</b>-p<b>][</b>-b <i>type</i><b>][</b>-d <i>delim</i><b>][</b>-f <i>type</i><b>][</b>-h <i>type</i><b>][</b>-i <i>incr</i><b>][</b>-l <i>num</i><b>][</b>-n <i>format</i><b>]
[</b>-s <i>sep</i><b>][</b>-v <i>startnum</i><b>][</b>-w <i>width</i><b>][</b><i>file</i><b>]</b>
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_1538">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>nl</i>
utility
reads lines from the named
<i>file</i>
or the standard input if no
<i>file</i>
is named and
reproduces the lines to standard output.
Lines are numbered on the left.
Additional functionality may be provided in accordance with
the command options in effect.
<p>
The
<i>nl</i>
utility views the text it reads in terms of logical pages.
Line numbering is reset at the start of each logical page.
A logical page consists of a header, a body and a footer section.
Empty sections are valid.
Different line numbering options are independently available
for header, body and footer (for example, no numbering of header and footer
lines while numbering blank lines only in the body).
<p>
The starts of logical page sections are signalled by input
lines containing nothing but the following delimiter characters:
<pre>
<table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Line</b>
<th align=center><b>Start of</b>
<tr valign=top><td align=left>\:\:\:
<td align=left>header
<tr valign=top><td align=left>\:\:
<td align=left>body
<tr valign=top><td align=left>\:
<td align=left>footer
</table>
</pre>
<p>
Unless otherwise specified,
<i>nl</i>
assumes the text being read is in a single logical page body.
</blockquote><h4><a name = "tag_001_014_1539">&nbsp;</a>OPTIONS</h4><blockquote>
The
<i>nl</i>
utility supports the <b>XBD</b> specification, <a href="../xbd/utilconv.html#usg"><b>Utility Syntax Guidelines</b>&nbsp;</a> ,
except that the options can be intermingled with the optional
<i>file</i>
operand.
Only one file can be named.
<p>
The following options are supported:
<dl compact>

<dt><b>-b&nbsp;</b><i>type</i>
<dd>Specify which logical page body lines are to be numbered.
Recognised
<i>types</i>
and their meaning are:
<dl compact>

<dt><b>a</b><dd>Number all lines.

<dt><b>t</b><dd>Number only non-empty lines.

<dt><b>n</b><dd>No line numbering.

<dt><b>p</b><i>string</i><dd>Number only lines that contain the basic regular expression
specified in
<i>string</i>.

</dl>
<p>
The default
<i>type</i>
for logical page body is
t
(text lines numbered).
<br>
<dt><b>-d&nbsp;</b><i>delim</i>
<dd>
Specify the delimiter characters that indicate the start of a logical page
section.
These can be changed from the default characters
\:
to
two user-specified characters.
If only one character is entered,
the second character remains the default character ":".
<br>
<dt><b>-f&nbsp;</b><i>type</i>
<dd>Specify the same as <b>b</b><i> type</i> except for footer.
The default for logical page footer is
n
(no lines numbered).
<br>
<dt><b>-h&nbsp;</b><i>type</i>
<dd>Specify the same as <b>b</b><i> type</i> except for header.
The default
<i>type</i>
for logical page header is
n
(no lines numbered).
<br>
<dt><b>-i&nbsp;</b><i>incr</i>
<dd>Specify the increment value used
to number logical page lines.
The default is 1.
<br>
<dt><b>-l&nbsp;</b><i>num</i>
<dd>Specify the number of blank lines to be considered as one.
For example,
<b>-l</b>2
results in only the second adjacent blank line
being numbered (if the appropriate
h<b>-a</b>,
<b>-b</b>a
or
<b>-f</b>a
option is set).
The default is 1.
<br>
<dt><b>-n&nbsp;</b><i>format</i>
<dd>
Specify the line numbering format.
Recognised values are:
<b>ln</b>,
left justified, leading zeros suppressed;
<b>rn</b>,
right justified, leading zeros suppressed;
<b>rz</b>,
right justified, leading zeros kept.
The default
<i>format</i>
is
<b>rn</b>
(right justified).
<br>
<dt><b>-p</b>
<dd>Specify that numbering should not be restarted at logical page delimiters.
<br>
<dt><b>-s&nbsp;</b><i>sep</i>
<dd>Specify the characters used in
separating the line number and the
corresponding text line.
The default
<i>sep</i>
is a tab.
<br>
<dt><b>-v&nbsp;</b><i>startnum</i>
<dd>
Specify the initial value used to
number logical page lines.
The default is 1.
<br>
<dt><b>-w&nbsp;</b><i>width</i>
<dd>
Specify the number of characters to be used for the line number.
The default
<i>width</i>
is 6.
<p>
</dl>
</blockquote><h4><a name = "tag_001_014_1540">&nbsp;</a>OPERANDS</h4><blockquote>
The following operand is supported:
<dl compact>

<dt><i>file</i><dd>A pathname of a text file to be line-numbered.

</dl>
</blockquote><h4><a name = "tag_001_014_1541">&nbsp;</a>STDIN</h4><blockquote>
The standard input is a text file that is used if no
<i>file</i>
operand is given.
</blockquote><h4><a name = "tag_001_014_1542">&nbsp;</a>INPUT FILES</h4><blockquote>
The input file named by the
<i>file</i>
operand is a text file.
</blockquote><h4><a name = "tag_001_014_1543">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>nl</i>:
<dl compact>

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.

<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_COLLATE</i><dd>
Determine the locale for the
behaviour of ranges, equivalence classes
and multi-character collating elements
within regular expressions.

<dt><i>LC_CTYPE</i><dd>
Determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single- as opposed to multi-byte characters
in arguments and input files),
the behaviour of character classes within regular expressions,
and for deciding which characters are in character class
<b>graph</b>
(for the
b<b>-t</b>,
<b>-f</b>t
and
<b>-h</b>t
options).


<dt><i>LC_MESSAGES</i><dd>
Determine the locale that should be used to affect
the format and contents of diagnostic
messages written to standard error.

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
</dl>
</blockquote><h4><a name = "tag_001_014_1544">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_1545">&nbsp;</a>STDOUT</h4><blockquote>
The standard output is a text file in the following format:
<p><code>
<tt>"%s%s%s"</tt>, &lt;<i>line&nbsp;number</i>&gt;,
&lt;<i>separator</i>&gt;,
&lt;<i>input&nbsp;line</i>&gt;
</code>
where
&lt;<i>line&nbsp;number</i>&gt;
is one of the following numeric formats:
<dl compact>

<dt><b>%6d</b><dd>when the
<b>rn</b>
format is used (the default; see
<b>-n</b>).

<dt><b>%06d</b><dd>when the
<b>rz</b>
format is used.

<dt><b>%-6d</b><dd>when the
<i><a href="ln.html">ln</a></i>
format is used.

<dt>&lt;empty&gt;<dd>
when line numbers are suppressed for a portion of the page; the
&lt;<i>separator</i>&gt;
is also suppressed.

</dl>
<p>
In the preceding list, the number 6 is the default width; the
<b>-w</b>
option can change this value.
</blockquote><h4><a name = "tag_001_014_1546">&nbsp;</a>STDERR</h4><blockquote>
Used only for diagnostic messages.
</blockquote><h4><a name = "tag_001_014_1547">&nbsp;</a>OUTPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1548">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_1549">&nbsp;</a>EXIT STATUS</h4><blockquote>
The following exit values are returned:
<dl compact>

<dt>0<dd>Successful completion.

<dt>&gt;0<dd>An error occurred.

</dl>
</blockquote><h4><a name = "tag_001_014_1550">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_1551">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
In using the
<b>-d</b>&nbsp;<i>delim</i>
option, care should be taken to escape characters that have special meaning
to the command interpreter.
</blockquote><h4><a name = "tag_001_014_1552">&nbsp;</a>EXAMPLES</h4><blockquote>
The command:
<pre>
<code>
nl  -v 10  -i 10  -d \!+  file1
</code>
</pre>
will number
<i>file1</i>
starting at line number 10 with an increment of 10.
The logical page delimiter is "!+".
Note that the "!" has to be escaped when using
<i>csh</i>
as a command interpreter because of its history substitution syntax.
For
<i>ksh</i>
and
<i><a href="sh.html">sh</a></i>
the escape is not necessary, but will not do any harm.
</blockquote><h4><a name = "tag_001_014_1553">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
The intermingling of the
<i>file</i>
operand with the options is an obsolescent feature that will be
removed from a future issue.
</blockquote><h4><a name = "tag_001_014_1554">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="pr.html">pr</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
